home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / open.n < prev    next >
Encoding:
Text File  |  1995-02-22  |  4.1 KB  |  126 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) open.n 1.3 95/02/22 14:27:29
  9. '\" 
  10. .so man.macros
  11. .HS open tcl 7.0
  12. .BS
  13. '\" Note:  do not modify the .SH NAME line immediately below!
  14. .SH NAME
  15. open \- Open a file
  16. .SH SYNOPSIS
  17. .VS
  18. \fBopen \fIfileName\fR ?\fIaccess\fR? ?\fIpermissions\fR?
  19. .VE
  20. .BE
  21.  
  22. .SH DESCRIPTION
  23. .PP
  24. This command opens a file and returns an identifier
  25. that may be used in future invocations
  26. of commands like \fBread\fR, \fBputs\fR, and \fBclose\fR.
  27. \fIFileName\fR gives the name of the file to open; if it starts with
  28. a tilde then tilde substitution is performed as described for
  29. \fBTcl_TildeSubst\fR.
  30. If the first character of \fIfileName\fR is ``|'' then the
  31. remaining characters of \fIfileName\fR are treated as a command
  32. pipeline to invoke, in the same style as for \fBexec\fR.
  33. In this case, the identifier returned by \fBopen\fR may be used
  34. to write to the command's input pipe or read from its output pipe.
  35. .PP
  36. The \fIaccess\fR argument indicates the way in which the file
  37. (or command pipeline) is to be accessed.
  38. .VS
  39. It may take two forms, either a string in the form that would be
  40. passed to the \fBfopen\fR library procedure or a list of POSIX
  41. access flags.
  42. It defaults to ``\fBr\fR''.
  43. In the first form \fIaccess\fR may have any of the following values:
  44. .VE
  45. .TP 15
  46. \fBr\fR
  47. Open the file for reading only; the file must already exist.
  48. .TP 15
  49. \fBr+\fR
  50. Open the file for both reading and writing; the file must
  51. already exist.
  52. .TP 15
  53. \fBw\fR
  54. Open the file for writing only.  Truncate it if it exists.  If it doesn't
  55. exist, create a new file.
  56. .TP 15
  57. \fBw+\fR
  58. Open the file for reading and writing.  Truncate it if it exists.
  59. If it doesn't exist, create a new file.
  60. .TP 15
  61. \fBa\fR
  62. Open the file for writing only.  The file must already exist, and the file
  63. is positioned so that new data is appended to the file.
  64. .TP 15
  65. \fBa+\fR
  66. Open the file for reading and writing.  If the file doesn't exist,
  67. create a new empty file.
  68. Set the initial access position  to the end of the file.
  69. .PP
  70. In the second form, \fIaccess\fR consists of a list of any of the
  71. .VS
  72. following flags, all of which have the standard POSIX meanings.
  73. One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR.
  74. .TP 15
  75. \fBRDONLY\fR
  76. Open the file for reading only.
  77. .TP 15
  78. \fBWRONLY\fR
  79. Open the file for writing only.
  80. .TP 15
  81. \fBRDWR\fR
  82. Open the file for both reading and writing.
  83. .TP 15
  84. \fBAPPEND\fR
  85. Set the file pointer to the end of the file prior to each write.
  86. .TP 15
  87. \fBCREAT\fR
  88. Create the file if it doesn't already exist (without this flag it
  89. is an error for the file not to exist).
  90. .TP 15
  91. \fBEXCL\fR
  92. If \fBCREAT\fR is also specified, an error is returned if the
  93. file already exists.
  94. .TP 15
  95. \fBNOCTTY\fR
  96. If the file is a terminal device, this flag prevents the file from
  97. becoming the controlling terminal of the process.
  98. .TP 15
  99. \fBNONBLOCK\fR
  100. Prevents the process from blocking while opening the file.
  101. For details refer to your system documentation on the \fBopen\fR system
  102. call's \fBO_NONBLOCK\fR flag.
  103. .TP 15
  104. \fBTRUNC\fR
  105. If the file exists it is truncated to zero length.
  106. .PP
  107. If a new file is created as part of opening it, \fIpermissions\fR
  108. (an integer) is used to set the permissions for the new file in
  109. conjunction with the process's file mode creation mask.
  110. \fIPermissions\fR defaults to 0666.
  111. .VE
  112. .PP
  113. If a file is opened for both reading and writing then \fBseek\fR
  114. must be invoked between a read and a write, or vice versa (this
  115. restriction does not apply to command pipelines opened with \fBopen\fR).
  116. When \fIfileName\fR specifies a command pipeline and a write-only access
  117. is used, then standard output from the pipeline is directed to the
  118. current standard output unless overridden by the command.
  119. When \fIfileName\fR specifies a command pipeline and a read-only access
  120. is used, then standard input from the pipeline is taken from the
  121. current standard input unless overridden by the command.
  122.  
  123. .SH KEYWORDS
  124. access mode, append, controlling terminal, create, file,
  125. non-blocking, open, permissions, pipeline, process
  126.